home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / PInterfaces / Translation.p < prev    next >
Text File  |  1996-05-01  |  12KB  |  316 lines
  1. {
  2.      File:        Translation.p
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT Translation;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __TRANSLATION__}
  28. {$SETC __TRANSLATION__ := 1}
  29.  
  30. {$I+}
  31. {$SETC TranslationIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __TYPES__}
  35. {$I Types.p}
  36. {$ENDC}
  37. {$IFC UNDEFINED __FILES__}
  38. {$I Files.p}
  39. {$ENDC}
  40. {$IFC UNDEFINED __COMPONENTS__}
  41. {$I Components.p}
  42. {$ENDC}
  43. {$IFC UNDEFINED __TRANSLATIONEXTENSIONS__}
  44. {$I TranslationExtensions.p}
  45. {$ENDC}
  46.  
  47. {$PUSH}
  48. {$ALIGN MAC68K}
  49. {$LibExport+}
  50.  
  51. {  enumerated types on how a document can be opened }
  52.  
  53. TYPE
  54.     DocOpenMethod                        = INTEGER;
  55.  
  56. CONST
  57.     domCannot                    = 0;
  58.     domNative                    = 1;
  59.     domTranslateFirst            = 2;
  60.     domWildcard                    = 3;
  61.  
  62. {  0L terminated array of OSTypes, or FileTypes }
  63.  
  64. TYPE
  65.     TypesBlock                            = ARRAY [0..63] OF OSType;
  66.     TypesBlockPtr                        = ^OSType;
  67. {  Progress dialog resource ID }
  68.  
  69. CONST
  70.     kTranslationScrapProgressDialogID = -16555;
  71.  
  72. {  block of data that describes how to translate }
  73.  
  74. TYPE
  75.     FileTranslationSpecPtr = ^FileTranslationSpec;
  76.     FileTranslationSpec = RECORD
  77.         componentSignature:        OSType;
  78.         translationSystemInfo:    Ptr;
  79.         src:                    FileTypeSpec;
  80.         dst:                    FileTypeSpec;
  81.     END;
  82.  
  83.     FileTranslationSpecArrayPtr            = ^FileTranslationSpec;
  84. {$IFC FOR_SYSTEM7_AND_SYSTEM8_COOPERATIVE }
  85. {
  86. ****************************************************************************************
  87. * 
  88. *   GetFileTypesThatAppCanNativelyOpen
  89. * 
  90. *  This routine returns a list of all FileTypes that an application can open by itself
  91. * 
  92. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  93. *             appSignature        signature (creator) of application
  94. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  95. * 
  96. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  97. }
  98. FUNCTION GetFileTypesThatAppCanNativelyOpen(appVRefNumHint: INTEGER; appSignature: OSType; VAR nativeTypes: FileType): OSErr;
  99.     {$IFC NOT GENERATINGCFM}
  100.     INLINE $701C, $ABFC;
  101.     {$ENDC}
  102. {
  103. ****************************************************************************************
  104. * 
  105. *  ExtendFileTypeList
  106. * 
  107. *  This routine makes a new list of file types that can be translated into a type in the given list
  108. *  Used by StandardFile
  109. * 
  110. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  111. *             numberOriginalTypes        number of file types in orgTypeList
  112. *              extendedTypeList        pointer to a buffer to be filled with file types
  113. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  114. * 
  115. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  116. *             numberExtendedTypes        number of file types put in extendedTypeList
  117. }
  118. FUNCTION ExtendFileTypeList({CONST}VAR originalTypeList: FileType; numberOriginalTypes: INTEGER; VAR extendedTypeList: FileType; VAR numberExtendedTypes: INTEGER): OSErr;
  119.     {$IFC NOT GENERATINGCFM}
  120.     INLINE $7009, $ABFC;
  121.     {$ENDC}
  122. {
  123. ****************************************************************************************
  124. * 
  125. * 
  126. *  This routine checks if a file can be opened by a particular application.
  127. *  If so, it returns if it needs to be translated first, and if so then how.
  128. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  129. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  130. * 
  131. *  Enter:    targetDocument        document to check if it can be opened
  132. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  133. *             appSignature        signature (creator) of application to open doc
  134. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  135. *             onlyNative            whether to consider if document can be translated before opening
  136. *             howToOpen            pointer to buffer in which to put how the document can be opened
  137. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  138. * 
  139. *  Exit:    howToOpen            whether file needs to be translated to be read
  140. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  141. *             returns                noErr, noPrefAppErr
  142. }
  143. FUNCTION CanDocBeOpened({CONST}VAR targetDocument: FSSpec; appVRefNumHint: INTEGER; appSignature: OSType; {CONST}VAR nativeTypes: FileType; onlyNative: BOOLEAN; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  144.     {$IFC NOT GENERATINGCFM}
  145.     INLINE $701E, $ABFC;
  146.     {$ENDC}
  147. {
  148. ****************************************************************************************
  149. * 
  150. *  GetFileTranslationPaths
  151. * 
  152. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  153. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  154. * 
  155. *  Enter:    srcDoc            source file or NULL for all matches
  156. *             dstDoc            destination FileType or NULL for all matches
  157. *             maxResultCount
  158. *             resultBuffer
  159. *  Exit:    number of paths
  160. }
  161. FUNCTION GetFileTranslationPaths(VAR srcDocument: FSSpec; dstDocType: FileType; maxResultCount: INTEGER; resultBuffer: FileTranslationSpecArrayPtr): INTEGER;
  162.     {$IFC NOT GENERATINGCFM}
  163.     INLINE $7038, $ABFC;
  164.     {$ENDC}
  165. {
  166. ****************************************************************************************
  167. * 
  168. *  GetPathFromTranslationDialog
  169. * 
  170. *  This routine, with a given document, application, and a passed typelist will display the
  171. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  172. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  173. *  The routine returns the translation path information.
  174. * 
  175. *  Enter:    theDocument            FSSpec to document to open
  176. *             theApplication        FSSpec to application to open document
  177. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  178. *                                 you would like the documented translated to.  Order most perferred
  179. *                                 to least.
  180. * 
  181. *  Exit:    howToOpen            Translation method needed to open document
  182. *             howToTranslate        Translation specification
  183. *             returns                Any errors that might occur.
  184. }
  185. FUNCTION GetPathFromTranslationDialog({CONST}VAR theDocument: FSSpec; {CONST}VAR theApplication: FSSpec; typeList: TypesBlockPtr; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  186.     {$IFC NOT GENERATINGCFM}
  187.     INLINE $7037, $ABFC;
  188.     {$ENDC}
  189. {
  190. ****************************************************************************************
  191. * 
  192. *   TranslateFile
  193. * 
  194. *  This routine reads a file of one format and writes it to another file in another format. 
  195. *  The information on how to translated is generated by the routine CanDocBeOpened.
  196. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  197. *  The destination file must not exist.  It is created by this routine.  
  198. * 
  199. *  Enter:    sourceDocument            input file to translate
  200. *             destinationDocument        output file of translation
  201. *             howToTranslate            pointer to info on how to translate
  202. *  Exit:    returns                    noErr, badTranslationSpecErr 
  203. }
  204. FUNCTION TranslateFile({CONST}VAR sourceDocument: FSSpec; {CONST}VAR destinationDocument: FSSpec; {CONST}VAR howToTranslate: FileTranslationSpec): OSErr;
  205.     {$IFC NOT GENERATINGCFM}
  206.     INLINE $700C, $ABFC;
  207.     {$ENDC}
  208. {
  209. ****************************************************************************************
  210. * 
  211. *   GetDocumentKindString
  212. * 
  213. *  This routine returns the string the Finder should show for the "kind" of a document
  214. *  in the GetInfo window and in the kind column of a list view.  
  215. * 
  216. *  Enter:    docVRefNum        The volume containing the document
  217. *             docType            The catInfo.fdType of the document
  218. *             docCreator        The catInfo.fdCreator of the document
  219. *             kindString        pointer to where to return the string
  220. * 
  221. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  222. *             returns            noErr, or afpItemNoFound if kind could not be determined
  223. }
  224. FUNCTION GetDocumentKindString(docVRefNum: INTEGER; docType: OSType; docCreator: OSType; VAR kindString: Str63): OSErr;
  225.     {$IFC NOT GENERATINGCFM}
  226.     INLINE $7016, $ABFC;
  227.     {$ENDC}
  228. {
  229. ****************************************************************************************
  230. * 
  231. *  GetTranslationExtensionName
  232. * 
  233. *  This routine returns the translation system name from a specified TranslationSpec
  234. * 
  235. *  Enter:    translationMethod    The translation path to get the translation name from
  236. * 
  237. *  Exit:    extensionName        The name of the translation system
  238. *             returns                Any errors that might occur
  239. }
  240. FUNCTION GetTranslationExtensionName({CONST}VAR translationMethod: FileTranslationSpec; VAR extensionName: Str31): OSErr;
  241.     {$IFC NOT GENERATINGCFM}
  242.     INLINE $7036, $ABFC;
  243.     {$ENDC}
  244. {
  245. ****************************************************************************************
  246. * 
  247. *  GetScrapDataProcPtr
  248. * 
  249. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  250. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  251. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  252. *  with a list all the formats that you have available to be translated, and the length of each.
  253. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  254. *  the formats that 'fmts' list said was available.
  255. * 
  256. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  257. *             dataH                    Handle in which to put the requested data
  258. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  259. *             
  260. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  261. }
  262.  
  263. TYPE
  264.     GetScrapDataProcPtr = ProcPtr;  { FUNCTION GetScrapData(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr): OSErr; }
  265.  
  266.     GetScrapDataUPP = UniversalProcPtr;
  267.  
  268. CONST
  269.     uppGetScrapDataProcInfo = $00000FE0;
  270.  
  271. FUNCTION NewGetScrapDataProc(userRoutine: GetScrapDataProcPtr): GetScrapDataUPP;
  272.     {$IFC NOT GENERATINGCFM }
  273.     INLINE $2E9F;
  274.     {$ENDC}
  275.  
  276. FUNCTION CallGetScrapDataProc(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr; userRoutine: GetScrapDataUPP): OSErr;
  277.     {$IFC NOT GENERATINGCFM}
  278.     INLINE $205F, $4E90;
  279.     {$ENDC}
  280.  
  281. TYPE
  282.     GetScrapData                        = GetScrapDataUPP;
  283. {
  284. ****************************************************************************************
  285. * 
  286. *  TranslateScrap
  287. * 
  288. *  This routine resizes the destination handle and fills it with data of the requested format.
  289. *  The data is generated by translated one or more source formats of data supplied by
  290. *  the procedure srcDataGetter.  
  291. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  292. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  293. * 
  294. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  295. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  296. *             destinationFormat            Format of data desired
  297. *             destinationData                Handle in which to store translated data
  298. *             
  299. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  300. }
  301. FUNCTION TranslateScrap(sourceDataGetter: GetScrapData; sourceDataGetterRefCon: UNIV Ptr; destinationFormat: ScrapType; destinationData: Handle; progressDialogID: INTEGER): OSErr;
  302.     {$IFC NOT GENERATINGCFM}
  303.     INLINE $700E, $ABFC;
  304.     {$ENDC}
  305. {$ENDC}
  306. {$ALIGN RESET}
  307. {$POP}
  308.  
  309. {$SETC UsingIncludes := TranslationIncludes}
  310.  
  311. {$ENDC} {__TRANSLATION__}
  312.  
  313. {$IFC NOT UsingIncludes}
  314.  END.
  315. {$ENDC}
  316.